How to Organize Your Technical Documentation

This guest blog post was written by Duncan Smith, Technical Communication Team Leader and Paul Ballard, Managing Director at 3di.

At 3di, we are faced with a wide range of customer challenges. We’ve worked out how to best organize technical documentation in a way that is flexible enough to meet each challenge, without us having to reinvent the wheel every time we win a new customer. We’ll share with you here some of the approaches and tools we use, organized into three key recommendations:

• Understand the value
• Build up assets
• Follow a process

Understand the Value

What’s the relationship between technical documentation and the rest of the business? What value do you want it to add? What business benefits do you want your technical documentation to deliver? You might not be a technical writer, but understanding the future experience someone will have with your process documentation is key. For example, maybe your priorities are related to:

• Improving your technical documentation so it better represents the product
• Making technical product information management in the business more efficient
• Improving the customer experience when they are using your products
• Writing API documentation for the development team to reuse common scripts
• Enabling self-service during product discovery, on-boarding, upgrades, and day-to-day use
• Ensuring you are compliant and meet regulations
• Make growing internationally easier by having technical documentation that is easier to translate
• Making a knowledge base for employees onboarding, roles/responsibilities, and org chart
• Or maybe, it would simply be nice to keep up with product releases!

Understanding what value you want your technical documentation to add will help inform your decisions about what’s worth investing in, and how much is worth changing.

Build up Assets

Whatever your context, if you are trying to organize technical documentation, you will need to build up your assets. At 3di these include:

• 3di Clear Communication Standard – the principles that underpin how we design, write and build information
• 3di Style Guide – how to approach specific writing decisions
• Content Models – the mix of content likely to solve common information needs
• Content Plans – for a specific technical document, what topics will it need to contain
• Templates – combining the above with a tool’s features
• Service Blueprints – how we engage with customers for each type of service

We’ve learned to be pragmatic, and patient. Building up assets that underpin how we work has been an iterative process, and I don’t think we are yet to find ourselves in a customer situation that runs exactly like the 3di playbook describes. But we try and learn what works, and what doesn’t, and feed that back into the design of our assets. Let’s look into three of these assets in a bit more detail.

3di Clear Communication Standard

This has become our collection of principles for writing well, and following principles like these will underpin your long-term ability to organize technical documentation and the people needed to create it. Our standard has been derived from multiple methodologies and published guidelines that are well-known within the technical writing profession, such as Information Mapping®, IBM’s Developing Quality Technical Information: A Handbook for Writers and Editors, and the Microsoft Style Guide.

Fig 1: Some of the principles that appear across methodologies and guidelines.

Content Models

We use the idea of a Content Model to make sure the range of content and documents we are going to write will actually meet genuine information needs for the target audience, and so deliver on the business value. The example below is from a recent project for a small software company, helping that business imagine how the recommended range of content types will hang together and feel like a coherent set of product information.

Fig 2: Example Content Model for a small software company.

Templates

Our template project for MadCap Flare provides a starting point for any new Flare projects, so authors can work with common file structures, styles, and other assets. Within our Flare template project, the Template Description contains guidance on what template files are available and how to use them.

The project includes:

• Template TOCs and template targets, for example, for manuals that are compliant with the Machinery Directive.
• Placeholder topics for common technical content that is required, such as frontmatter for PDF outputs or landing pages for HTML outputs.
• Stylesheets, page layouts, skins and more that are ready to adapt to meet a customer’s branding and design requirements.

Fig 3: Screenshot from the 3di MadCap Flare template project.

Follow a Process

Whether or not you have any assets already or know what you are trying to achieve, the simplest way to start organizing technical documentation is to decide on a documentation process and follow it as consistently as you can.

What we mean here is that it’s possible you are reading this blog in a situation where it feels like your project documentation is disorganized, or that the approach is more like a scatter-gun; responding to each business demand as it arises. We have found having a simple business process, that we deploy every time, really helps to keep our own team organized and the businesses we are serving seem to respect the activities we explain need to be carried out.

We’ve honed our process over the years, but this is it:

Fig 4: 3di’s summary process for organizing project documentation.

Your documentation process could of course be different, but deciding on a process, telling your team and external stakeholders this is your process, and then trying to follow it consistently will make a world of difference. Our process is not radical but it is simple and can be applied at lots of different levels and in a wide range of contexts–which suits us.

The Process in Action

Let’s imagine a scenario: you’re leading a small in-house team of technical writers and the company has just acquired a new product line. Their technical documents are no match for your beautifully crafted outputs so you have been asked to work your magic.

Analysis

Considerations might include:

• Intended Audience–who are the users?
• Context–how will they access and use the information?
• Standards and guidelines–what prerequisites are there?
• Preconceptions–what’s the legacy relationship between the products and docs we are dealing with?
• Production process–how are the product and the documentation currently created?

Design

Combine your Analysis with your Assets to reach conclusions and make recommendations about how to make things better for your new colleagues. The fact that you have done and shared Analysis before you’ve made recommendations will make them much more likely to accept your Design. Your recommendations might include:

• Which Content Model is going to work best?
• What technical documentation software should we deploy?
• What workflow will be most efficient?
• What content could you reuse?
• How should we meet the regulatory requirements?
• Who’s going to do the work?
• How best to get a return on the budget invested?

Prototype

Agree with your new colleagues, what could be used to test out the Design. Good candidates are small, self-contained, and useful for demonstrating the new improved future over 1-2 months. I recommend against reworking legacy content; it won’t be a way to test live workflows, and there’ll likely be bad design built in that will be hard to refactor. So, go for a forthcoming launch of a new feature or small module; something the business is investing in currently and wants to succeed.

You’re trying to test out each element of the Design and giving your new colleagues the chance to feedback before you all press on with the bigger Implementation.

Implementation

This is where you get on with applying the agreed Design across the full product range – probably over several months, getting everyone used to the implications of the decisions that have been made, for example:

• New Jira workflows
• Minimum viable product expectations for supporting releases
• Marketing and customer support teams reusing the improved content in their outputs
• Quicker turnaround of applying branding and product name changes
• Starting to embed the improved content into new product UIs

Transition to Business-As-Usual (BAU)

So, in our imagined scenario, you have dragged the acquired product line’s technical documentation capability kicking and screaming into the modern world, and now you need to sustain the effort (it needs to feel like a new Business-As-Usual) and agree on a roadmap for continuing the improvements. In our experience, Implementation and Transition to BAU often run in parallel, but I suggest you aim to achieve the new BAU state within 6-12 months.

Keep Moving Forward

We’ve made the case that organizing technical documentation combines a clear understanding of the value you want, with a set of assets, and a clear process. We’ve seen this combination work for our customers over many years, and across several industries that utilize technical writing services. Crucially, each element of technical documentation software needs to evolve and keep pace with how each customer is changing, and with what the users and market expects. In addition, referring back to various technical documentation examples is a beneficial action to take as well. When you think you have organized technical documentation it can be hard to keep up the momentum and this is why we use the idea of a roadmap during the Transition to BAU, targeting continuous improvement over the next 1-2 years. Achieving organized technical documentation using the right knowledge base software is an investment, but a rewarding one. Good luck with yours.